What & why

The storage-format upgrade refusal told operators to export with "the older omnigraph binary that created it" without saying which release — leaving them to guess, and stuck if the fleet was already upgraded. This names the exact release line that wrote each internal-schema stamp (e.g. v3 → 0.6.2–0.7.2) plus the precise export/init/load commands, keeping the strand-model upgrade fail-closed but self-service. The message is engine-shared, so server boot-quarantine logs and cluster status observations get the better text for free.

Backing issue / RFC

• Trivial fast-lane — a focused UX/docs improvement to the already-documented export/import upgrade path; no architecture change and the strand model is untouched. (Maintainer internal process applies.)

Checklist

• Change is focused (one logical change)
• Tests added/updated for behavior changes — in-source refusal assertion (red→green) + a gated genuine-v3 cross-version round-trip test
• Public docs updated — upgrade.md (release-named message + stamp→release table), versioning.md, testing.md
• Reviewed against docs/dev/invariants.md — no Hard Invariant weakened; the refusal is still fail-closed in both directions; in-engine read of old formats was deliberately NOT added

Notes for reviewers

• Stamp→release map is derived from the release tags (verified: v3 starts at 0.6.2, not 0.7.0).
• crates/omnigraph-cli/tests/crossversion_upgrade.rs mints a real v3 graph with omnigraph 0.7.2 and is gated on OMNIGRAPH_OLD_BIN; it skips in the default suite and runs in the new gated crossversion_upgrade CI job (installs omnigraph-cli@0.7.2). It is the empirical proof the existing stamp-rewind test can't give.

Greptile Summary

This PR improves the operator experience for the storage-format upgrade path by making the sub-CURRENT refusal message self-service: it now names the exact release line that wrote each internal-schema stamp (via release_for_internal_schema_version in migrations.rs) and prints the full export → init → load command sequence. No behavioral change to the strand model or open-path logic.

• Core code change (migrations.rs): a new release_for_internal_schema_version(stamp) function maps v1–v4 stamps to release strings; refuse_if_stamp_unsupported embeds this in the sub-CURRENT error so operators know which binary to fetch.
• Test coverage: tests.rs asserts the named release appears in the refusal; crossversion_upgrade.rs (gated on OMNIGRAPH_OLD_BIN) mints a genuine v3 graph with the 0.7.2 binary and verifies the refusal text plus a full round-trip including a Vector column.
• Docs update: upgrade.md adds the stamp→release table (now covering v1–v4), reproduces the updated error message verbatim, and documents versioning.md and testing.md to reflect the new function and CI job.

Confidence Score: 5/5

Safe to merge — the change is limited to the text of an existing error message and its surrounding documentation; the refusal logic itself is untouched and still fail-closed.

The only code path changed is the string returned by the new release_for_internal_schema_version function and its embedding in the error message. The open-path guard, stamp comparison, and MIN_SUPPORTED == CURRENT invariant are all unchanged. Tests cover the new assertion both in-source (synthetic stamp rewind) and via a real cross-version binary.

The 4 => "0.8.x" arm in migrations.rs differs from the "0.8.x and later" wording in upgrade.md — a minor drift that only matters once a future release maintains v4 without updating the string.

Important Files Changed

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Omnigraph::open / open_read_only] --> B[read_stamp from __manifest]
    B --> C{stamp vs CURRENT}
    C -->|stamp > CURRENT| D["Error: upgrade omnigraph\nbefore opening this graph"]
    C -->|stamp == CURRENT| E[Open succeeds]
    C -->|stamp < MIN_SUPPORTED| F[release_for_internal_schema_version stamp]
    F --> G{Match stamp}
    G -->|1| H["0.3.1 or earlier"]
    G -->|2| I["0.4.1 to 0.6.1"]
    G -->|3| J["0.6.2 to 0.7.2"]
    G -->|4| K["0.8.x"]
    G -->|_| L["an unrecognized older release"]
    H & I & J & K & L --> M["Error: __manifest stamped at v{stamp}...\nThis graph was created by omnigraph {release}.\nRebuild: export → init → load"]

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[Omnigraph::open / open_read_only] --> B[read_stamp from __manifest]
    B --> C{stamp vs CURRENT}
    C -->|stamp > CURRENT| D["Error: upgrade omnigraph\nbefore opening this graph"]
    C -->|stamp == CURRENT| E[Open succeeds]
    C -->|stamp < MIN_SUPPORTED| F[release_for_internal_schema_version stamp]
    F --> G{Match stamp}
    G -->|1| H["0.3.1 or earlier"]
    G -->|2| I["0.4.1 to 0.6.1"]
    G -->|3| J["0.6.2 to 0.7.2"]
    G -->|4| K["0.8.x"]
    G -->|_| L["an unrecognized older release"]
    H & I & J & K & L --> M["Error: __manifest stamped at v{stamp}...\nThis graph was created by omnigraph {release}.\nRebuild: export → init → load"]

_{Reviews (6): Last reviewed commit: "docs: self-service upgrade message + gat..." | Re-trigger Greptile}